docs: deixa explícito que o callback é opcional, e corrige a promessa de ordem

[NullSablex]

Duas coisas que a documentação dizia mal. As duas foram verificadas rodando um gamemode de teste num servidor SA-MP com MariaDB de verdade, não por leitura de código.

1. O callback é opcional — e ninguém percebia

Não-bloqueante não obriga a escrever callback para tudo. As oito natives que aceitam callback aceitam com padrão "", e sem ele a query roda e o resultado é descartado:

mysql_query(g_mysql, "UPDATE players SET last_login = NOW() WHERE id = 1");

Uma linha, sem forward, sem public, e o servidor não trava. Verificado: o UPDATE rodou e o banco ficou com o valor novo.

As duas exceções são mysql_hash_password e mysql_verify_password: callback obrigatório, sem valor padrão, e já recusado em runtime com aviso no log — o hash só existe através dele.

O problema não era falta de informação, era onde ela estava. Havia uma subseção ### Fire and forget no fim da página de queries, enquanto:

• a primeira linha da página dizia "o callback é invocado num tick posterior", como se sempre houvesse um;
• nenhum dos onze exemplos mostrava a forma sem callback, nem nos UPDATE;
• o README destacava "All queries are non-blocking" sem dizer o que isso implica para quem escreve.

Quem lia saía convencido do contrário. É a origem da reclamação de que o plugin "obriga a encher o código de callback".

2. A garantia de ordem é de callback, não de execução

mysql_query é FIFO na entrega dos callbacks. A execução não é ordenada: submit_query faz thread::spawn por query, cada uma pegando uma conexão do pool na hora. Duas submetidas em sequência rodam ao mesmo tempo no servidor.

O teste deixou isso claro:

4 comandos de schema disparados sem callback
ERRO em [INSERT INTO t_ordem...]: Table 'cbtest.t_ordem' doesn't exist
ERRO em [UPDATE t_ordem...]:      Table 'cbtest.t_ordem' doesn't exist

E a tabela comparativa ainda recomendava mysql_query para "SELECT chains that depend on order" — exatamente o uso que quebra.

A página agora diz qual ferramenta serializa de verdade, as duas confirmadas no mesmo teste:

Necessidade	Ferramenta	Verificado
Schema, migrações, .sql	mysql_query_file	id=1 v=20, ordem correta
Escritas dependentes	mysql_transaction_*	id=1 v=60, ordem correta
Leitura que depende de escrita	callback da escrita	—

Mudanças

• README.md — o destaque de "non-blocking" agora diz que o callback é opcional; o quick start mostra as duas formas lado a lado.
• docs/queries.md — abertura reescrita, seção de ordem com o exemplo que quebra e a tabela de alternativas, e a linha enganosa da tabela comparativa corrigida (mais uma linha nova, "Execution order: not ordered").
• include/mysql_samp.inc.in — @param callback agora diz "Optional" ou "REQUIRED" em cada caso. Vem do template, então chega aos dois includes gerados e ao hover do PawnPro.
• examples/12_no_callback.pwn — fire-and-forget, e o lembrete de que OnQueryError continua chegando.
• examples/13_ordering.pwn — o que é ordenado, o que não é, e o que usar no lugar.
• examples/README.md — os dois na tabela, mais uma nota no topo.

Verificação

• cargo test — 177 passed, 1 ignored
• mkdocs build --strict — sem links quebrados
• Guarda de codificação — OK, 21 arquivos
• Os dois exemplos novos compilam no pawncc sem erro