v2: подробные комментарии во всех модулях — что, зачем, контракты

v2/src/db/queries.js

@@ -1,6 +1,23 @@
 // ═══════════════════════════════════════════════════════════════════════════════
-// V2 — SQL-запросы (единственное место работы с БД)
-// Все функции работают с таблицами v2_companies, v2_entries, v2_audit
+// V2 — SQL-запросы
+//
+// ЭТО: единственное место где выполняется SQL.
+// НЕ: валидация (в crud/), бизнес-логика (в crud/).
+//
+// ЗАЧЕМ:
+//   1. Все SQL-запросы в одном файле — легко аудировать.
+//   2. Транзакции (BEGIN/COMMIT/ROLLBACK) только здесь.
+//   3. Фронтенды не видят SQL — только через crud API.
+//
+// ЧТО ПРИНИМАЕТ:
+//   companyId — внутренний id из v2_companies (число).
+//   cidr — УЖЕ проверенный CIDR (валидация в crud/).
+//   email, impBy — для аудита.
+//
+// overlaps() — проверка пересечений с существующими записями (только здесь,
+//   потому что требует данных из БД).
+//
+// ТАБЛИЦЫ: v2_companies, v2_entries, v2_audit (префикс v2_ — изоляция).
 // ═══════════════════════════════════════════════════════════════════════════════
 
 const { pool } = require('./index');