docs: update documentation for cart implementation

Updated API reference, error handling, and architecture docs to reflect
the new persistent cart system with database storage.

API Reference Updates (shop-api-reference.md):
- Updated last modified date to 2025-11-23
- Updated cart response schemas to match CartResponse/CartItemResponse models
- Added detailed schema tables for all cart endpoints
- Documented all cart exceptions with examples (CART_ITEM_NOT_FOUND, INSUFFICIENT_INVENTORY_FOR_CART, etc.)
- Added implementation notes about cart persistence and duplicate prevention
- Updated all endpoint documentation with proper request/response schemas
- Added CartOperationResponse and ClearCartResponse documentation

Error Handling Updates (error-handling.md):
- Added Shopping Cart Exceptions section with 6 cart-specific exceptions
- Added Product Exceptions section
- Added Inventory Exceptions section
- Updated error response format to show structured WizamartException format
- Added examples with error_code, message, status_code, and details fields
- Documented the difference between structured and generic error formats

Architecture Updates (overview.md):
- Added cart_items table to database schema diagram
- Documented session-based shopping cart in data model hierarchy

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

docs/api/error-handling.md

@@ -46,16 +46,64 @@ from app.exceptions import (
 |-----------|-------------|-------------|
 | `RateLimitException` | 429 | Too many requests, rate limit exceeded |
 
+### Shopping Cart Exceptions
+
+| Exception | Status Code | Description |
+|-----------|-------------|-------------|
+| `CartItemNotFoundException` | 404 | Cart item not found (product not in cart) |
+| `InsufficientInventoryForCartException` | 400 | Product doesn't have enough inventory for cart operation |
+| `InvalidCartQuantityException` | 422 | Cart quantity is invalid (e.g., less than min or greater than max) |
+| `CartValidationException` | 422 | Cart data validation failed |
+| `EmptyCartException` | 422 | Operation attempted on empty cart |
+| `ProductNotAvailableForCartException` | 400 | Product is not available for adding to cart |
+
+### Product Exceptions
+
+| Exception | Status Code | Description |
+|-----------|-------------|-------------|
+| `ProductNotFoundException` | 404 | Product not found in vendor catalog |
+| `ProductNotActiveException` | 400 | Product is inactive and cannot be purchased |
+
+### Inventory Exceptions
+
+| Exception | Status Code | Description |
+|-----------|-------------|-------------|
+| `InventoryNotFoundException` | 404 | Inventory record not found |
+| `InsufficientInventoryException` | 400 | Not enough inventory for operation |
+
 ## Error Response Format
 
-All errors return a consistent JSON format:
+All custom exceptions (inheriting from `WizamartException`) return a structured JSON format:
 
 ```json
 {
-  "detail": "Error message describing what went wrong",
-  "status_code": 401,
-  "timestamp": "2024-11-16T13:00:00Z",
-  "path": "/api/v1/auth/login"
+  "error_code": "PRODUCT_NOT_FOUND",
+  "message": "Product with ID '123' not found in vendor 1 catalog",
+  "status_code": 404,
+  "details": {
+    "resource_type": "Product",
+    "identifier": "123",
+    "product_id": 123,
+    "vendor_id": 1
+  }
+}
+```
+
+**Standard Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `error_code` | string | Machine-readable error code (e.g., "CART_ITEM_NOT_FOUND") |
+| `message` | string | Human-readable error message |
+| `status_code` | integer | HTTP status code |
+| `details` | object | Additional context-specific error details |
+
+**Note:** Generic FastAPI/HTTP errors may still use the simpler format:
+
+```json
+{
+  "detail": "Error message",
+  "status_code": 401
 }
 ```