docs: clarify DATABASE_URL vs DB_PATH precedence (#206)

.env.example

@@ -2,13 +2,21 @@
 ENVIRONMENT=development
 
 # ==================== Database ====================
-# PostgreSQL takes precedence when DATABASE_URL is set.
-# Leave empty for local SQLite development.
+# Choose ONE backend:
+#
+# 1) PostgreSQL (recommended for shared/production deployments)
+#    Set DATABASE_URL and leave DB_PATH unused.
+#    Example:
+#    DATABASE_URL=postgresql://ai_trader:change-me@127.0.0.1:5432/ai_trader
+#
+# 2) SQLite (local-only quick start)
+#    Leave DATABASE_URL empty. The API uses DB_PATH below.
+#
+# Precedence: if DATABASE_URL is non-empty, PostgreSQL is used and DB_PATH is ignored.
+# Unit tests may set ALLOW_SQLITE=true when exercising SQLite helpers.
 DATABASE_URL=
-# Example PostgreSQL URL:
-# DATABASE_URL=postgresql://ai_trader:change-me@127.0.0.1:5432/ai_trader
 
-# SQLite fallback path when DATABASE_URL is empty.
+# SQLite file path — only used when DATABASE_URL is empty.
 DB_PATH=service/server/data/clawtrader.db
 
 # ==================== API Keys ====================

README.md

@@ -121,6 +121,19 @@ Start your trading journey with zero risk:
 
 ---
 
+## Self-hosting (database)
+
+Copy `.env.example` to `.env` and choose **one** database backend:
+
+| Mode | Config | When to use |
+|------|--------|-------------|
+| **PostgreSQL** | Set `DATABASE_URL=postgresql://...` | Shared or production deployments |
+| **SQLite** | Leave `DATABASE_URL` empty; uses `DB_PATH` | Local quick start only |
+
+If `DATABASE_URL` is set, PostgreSQL is used and `DB_PATH` is ignored.
+
+---
+
 ## Architecture
 
 ```