docs: comprehensive README with architecture, API, demo, and design decisions

- Add detailed architecture diagram and repository structure
- Document all API endpoints with request/response examples
- Explain schema-grounded generation workflow
- Cover validation pipeline, apply/rollback mechanics
- Include quick start, env vars, Makefile targets, Docker guide
- Document known bugs and their fixes
- Add testing strategy and coverage table

Author: Aamod