feat: consolidate ledger trade writes into portfolio_ledger

- add ledger consolidation migration and remove ledger_trades usage
- return portfolio state after v1 ledger trade writes
- deprecate legacy buy/sell endpoints with deprecation headers
- add BAT-016, DCY-006, and REQ-036~038 documentation
- update repository models and tests for unified ledger entries

tests/test_auth.py

@@ -60,6 +60,23 @@ def test_trade_route_rejects_read_token(monkeypatch) -> None:
     assert response.json()["detail"] == "Insufficient permission"
 
 
+def test_legacy_buy_sell_routes_emit_deprecation_header(monkeypatch) -> None:
+    monkeypatch.setenv("PORTFOLIOHUB_DB_ENABLED", "false")
+    monkeypatch.setenv("PORTFOLIOHUB_TRADE_WRITE_TOKENS", "trade-token")
+    get_settings.cache_clear()
+    client = _client_with_tokens()
+
+    for path in ("/portfolios/p1/buy", "/portfolios/p1/sell"):
+        response = client.post(
+            path,
+            headers={"Authorization": "Bearer trade-token"},
+            json={"quantity": 1, "price": 1000, "fee": 0, "tax": 0, "note": ""},
+        )
+
+        assert response.status_code == 501
+        assert response.headers["Deprecation"] == "true"
+
+
 def test_admin_route_accepts_admin_token(monkeypatch) -> None:
     monkeypatch.setenv("PORTFOLIOHUB_DB_ENABLED", "false")
     monkeypatch.setenv("PORTFOLIOHUB_ADMIN_TOKENS", "admin-token")