docs: add guidelines for choosing Java vs Python API

[anshuman9468]

This PR adds documentation to help users decide between the Java and Python APIs by
clearly outlining their respective strengths, limitations, and recommended use cases.

The documentation includes:

• A comparison of the Java and Python APIs with practical pros and cons
• Guidelines on when to choose each API based on performance, scalability, and development needs
• A summary table for quick reference

This aims to improve clarity for new users and reduce ambiguity when selecting an API
for real-world projects.

Addresses #437
Issue Link-: #437

This PR only updates documentation and does not modify Python or runtime code.
The failing it-python checks appear unrelated and likely due to CI flakiness.
Requesting a rerun of the failing jobs.

Documentation Impact

• doc-included
• doc-needed
• doc-not-needed

[github-actions]

@anshuman9468 Please add the following content to your PR description and select a checkbox:

- [ ] `doc-needed` 
- [ ] `doc-not-needed` <!-- Your PR changes do not impact docs -->
- [ ] `doc-included`