Update documentation to reflect interactive rating system and API changes

- Update README.md with interactive rating system details
- Document zero-rating behavior in GET /api/ebooks/:id/rating
- Add comprehensive rating system documentation section
- Update Bruno collection files to reflect new API behavior
- Enhance API testing documentation with rating 0 fallback

README.md

@@ -11,7 +11,7 @@ A self-hosted ebook management system built with Go, PostgreSQL, HTMX, and Tailw
 - **🌙 Multiple Themes**: 11 beautiful themes including Tokyo Night, Dracula, Nord, Solarized Dark, Monokai, One Dark Pro, Material Dark, and Catppuccin variants (Mocha, Macchiato, Frappé, Latte) with user preferences saved to database
 - **🎨 Theme Persistence**: User theme choices sync between browser and server
 - **📖 Reading Progress**: User-specific reading progress tracking
-- **⭐ User Ratings**: Rate and review ebooks with personalized rating system
+- **⭐ Interactive Rating System**: 5-star rating system with interactive dashboard controls and zero-rating fallback
 - **📁 Multiple Folder Support**: Configure multiple ebook folders per user for comprehensive library management
 - **🔍 Enhanced Scanner**: Intelligent ebook discovery with Calibre folder structure support and comprehensive metadata extraction
 - **👀 Real-Time Monitoring**: File system monitoring for automatic ebook detection and updates
@@ -161,9 +161,9 @@ The application uses Go HTML templates for server-side rendering with HTMX for d
 - `PUT /api/ebooks/:id/progress` - Update reading progress
 
 ### Ratings (Protected)
-- `GET /api/ebooks/:id/rating` - Get user's rating for ebook
-- `POST /api/ebooks/:id/rating` - Create or update ebook rating
-- `PUT /api/ebooks/:id/rating` - Create or update ebook rating
+- `GET /api/ebooks/:id/rating` - Get user's rating for ebook (returns 0 when no rating exists)
+- `POST /api/ebooks/:id/rating` - Create or update ebook rating (1-5 stars)
+- `PUT /api/ebooks/:id/rating` - Create or update ebook rating (1-5 stars)
 - `DELETE /api/ebooks/:id/rating` - Delete user's rating
 - `GET /api/ebooks/:id/ratings` - Get all ratings for ebook
 
@@ -172,6 +172,33 @@ The application uses Go HTML templates for server-side rendering with HTMX for d
 - `POST /api/scanner/start` - Start real-time monitoring of configured folders
 - `POST /api/scanner/stop` - Stop real-time folder monitoring
 
+## ⭐ Interactive Rating System
+
+Bookmann features a fully interactive 5-star rating system integrated directly into the dashboard:
+
+### Rating Scale
+- **1-5 stars**: Standard rating scale for ebooks
+- **0 stars**: Automatically shown when no rating exists
+- **User-specific**: Each user has their own ratings per ebook
+
+### Dashboard Integration
+- **Visual Rating Display**: Interactive star widgets for each ebook
+- **Click-to-Rate**: Simply click on stars to set/update ratings
+- **Real-time Updates**: Rating changes reflect immediately without page reload
+- **Graceful Fallback**: Shows empty stars (☆) for unrated books
+
+### API Behavior
+- **GET /api/ebooks/:id/rating**: Returns rating 0 (HTTP 200) when no rating exists
+- **POST/PUT /api/ebooks/:id/rating**: Create or update ratings (1-5)
+- **DELETE /api/ebooks/:id/rating**: Remove user's rating
+- **pgx v5 Standards**: All database operations use modern pgx error handling
+
+### Frontend Features
+- **HTMX Integration**: Smooth interactions without full page refreshes
+- **Responsive Design**: Mobile-friendly rating controls
+- **Theme Support**: Rating stars adapt to user's selected theme
+- **Error Handling**: Graceful degradation when API calls fail
+
 ## 📁 Enhanced Ebook Scanner
 
 Bookmann includes an intelligent ebook scanner with full Calibre integration and smart folder structure detection.
@@ -312,7 +339,7 @@ Use the included Bruno collection in the `bruno/` directory for testing the API:
 - **Multiple Folder Support**: Users can configure multiple ebook directories with per-user folder management
 - **Real-Time Monitoring**: File system watching for automatic ebook updates with dynamic subfolder detection
 - **Scan Settings**: User-configurable scan frequency and auto-scan options
-- **Rating System**: User-specific ebook ratings with full CRUD operations
+- **Interactive Rating System**: 5-star dashboard controls with click-to-rate functionality, zero-rating fallback, and full CRUD operations
 
 ### Frontend Redesign
 - **Beautiful Homepage**: Hero section with features showcase and modern design