Documentation improvements and code cleanup

This issue tracks improvements to the project documentation and general code cleanup tasks:

- Update README with clearer setup instructions
- Add code comments for better maintainability
- Improve error handling in core modules
- Add examples for common use cases

This will help new contributors get started more easily and improve overall code quality.