feat: update documentation with project details, deployment instructions, and database concurrency management

Co-authored-by: Copilot <copilot@github.com>

docs/8.2-database.md

@@ -0,0 +1,46 @@
+# DuckDB Concurrency and Storage
+
+## Single Writer Per Process
+
+DuckDB allows only one process to open the database file in read-write mode at a time. The FastAPI backend must be run with a single worker (`uvicorn --workers 1`). Running multiple workers against the same DuckDB file will cause startup errors.
+
+## asyncio.Lock for Writes
+
+All database write operations (`INSERT`, `UPDATE`, `DELETE`) in the FastAPI async context are wrapped in a single `asyncio.Lock` (`get_write_lock()` from `backend/app/db.py`). This prevents concurrent coroutines from issuing overlapping writes within the single process, which would otherwise raise DuckDB optimistic concurrency errors.
+
+Read operations (`SELECT`) do not require the lock — DuckDB's MVCC provides consistent read snapshots.
+
+## Schema
+
+```sql
+CREATE TABLE users (
+    id            UUID      DEFAULT uuid() PRIMARY KEY,
+    email         VARCHAR   NOT NULL UNIQUE,
+    password_hash VARCHAR   NOT NULL,
+    role          VARCHAR   DEFAULT 'user',
+    created_at    TIMESTAMP DEFAULT now(),
+    updated_at    TIMESTAMP DEFAULT now()
+);
+
+CREATE TABLE refresh_tokens (
+    jti        UUID      DEFAULT uuid() PRIMARY KEY,
+    user_id    UUID      NOT NULL,           -- soft FK to users.id
+    issued_at  TIMESTAMP DEFAULT now(),
+    expires_at TIMESTAMP NOT NULL,
+    revoked    BOOLEAN   DEFAULT false
+);
+```
+
+> The `REFERENCES users(id)` foreign key is intentionally omitted from `refresh_tokens`. DuckDB fires FK checks on `UPDATE` of the parent table (including email changes), causing false constraint violations. Referential integrity is enforced manually: deleting a user also deletes their refresh tokens in the same write transaction.
+
+## Access Tokens
+
+Access tokens are **stateless** JWTs — not stored in the database. They are validated by signature and expiry claim only. The short TTL (15 minutes) limits the blast radius if a token is leaked.
+
+## Refresh Tokens
+
+Refresh tokens store a JTI (JWT ID) UUID in the `refresh_tokens` table. On each use the old JTI is revoked and a new one issued (rotation). On logout the JTI is immediately revoked. Expired and revoked tokens can be purged via `POST /admin/tokens/purge`.
+
+## Future: AI Generation History
+
+AI generation metadata (model, prompt, cost, result URLs) can be stored as JSON columns in a future `generation_history` table in DuckDB, enabling per-user analytics and usage dashboards at zero extra infrastructure cost.