Add code comments and improve error messages

[francescobianco]

• Added class-level and method-level documentation to all files in src/
• Introduced TODO comments for graceful error message improvements in Client and OauthClient
• Added TODO in Exception class to utilize setServerResponse method for structured error context
• All comments follow PHPDoc standards and are concise
• Error TODOs suggest specific improvements: connection context, structured error details, and auth-specific hints

📋 Description

Brief description of the changes made in this PR.

✨ Type of Change

• 🐛 Bug fix (fixes an issue)
• ✨ New feature (adds functionality)
• 🔧 Refactoring (code restructuring without functional changes)
• 📚 Documentation (updates to documentation)
• 🧪 Tests (adding or modifying tests)
• 🔒 Security (security-related fixes)
• ⚡ Performance (performance improvements)
• 🎨 Style (formatting changes, no logic changes)

🔍 Main Changes

🧪 Testing

• I have tested the changes locally
• I have added/updated unit tests
• All tests pass (./vendor/bin/phpunit)
• I have verified PHP 8.0+ compatibility

📝 Additional Notes

Any additional information, considerations, or important context for reviewers.

🔗 Related Issue

Closes #[issue_number] (if applicable)

📸 Screenshots (if applicable)

If changes affect the interface or visible behavior, include screenshots.

✅ Checklist

• My code follows the project conventions
• I have performed a self-review of my code
• I have commented complex code where necessary
• Documentation has been updated (if needed)
• I have not introduced breaking changes (or documented them)
• I have verified no sensitive information is in the code